Integration Guide Universal Robots PolyScope X LS 1.5 (URCap)

This guide describes how to integrate Universal Robots controllers that run PolyScope X with Locator Studio (LS) 1.5 through the Photoneo Locator Studio URCap (URCap version 1.5.5, protocol version 1.5.0). You install the URCap once on each robot controller. It adds the Photoneo settings page and the Photoneo program nodes to the teach pendant.

Note

For the general concept of the communication, see the Robot communication overview. The supported versions of all Robot modules are listed in the Robot module support matrix.

There is also a script-only variant of this Robot module, where every .urpx program contains its own copy of the library. See Integration Guide Universal Robots PolyScope X LS 1.5. Both variants use the same protocol. You can use both in one cell, but not in one program.

1. Prerequisites

The Locator Studio Robot module for PolyScope X is a URCap, locator-studio-1.5.5.urcapx, and a set of .urpx example programs. You install the URCap once on each robot controller. It adds:

• the Photoneo Locator Studio settings page on the Application tab. This page contains the vision controller address and the approach defaults. It adds the photoneo_locator_X.script library and the connect call to the beginning of every program.

• seven Locator program nodes in the Toolbox. They generate the pho_* requests, so you build a Locator Studio program from program tree lines and do not write script nodes by hand.

Before you start, make sure that your system meets these requirements:

• A Universal Robots e-Series robot with PolyScope X system software

• PolyScope X version 10.12.1 or higher

• A free Ethernet port on the robot controller for the connection to the Photoneo vision controller

• The Real-Time Data Exchange (RTDE) interface is enabled on the robot controller (see section 2.2)

• A USB flash drive to copy the .urcapx URCap and the .urpx example programs to the robot controller

• A Photoneo vision controller with Locator Studio that supports communication protocol 1.5.0

• A Locator Studio solution with at least one calibrated vision system and a configured localization

• MotionCam-3D for the dynamic MultiView (Instant Meshing) example. All other examples work with any supported Photoneo 3D sensor.

Note

A URCap is built for one version of the PolyScope X contribution API. A URCap that is built for a newer API may not install on an older robot controller. This URCap was built with the PolyScope X SDK 6.0.27 and the contribution API 42.2.3. If your robot controller has an older PolyScope X version, ask Photoneo for a matching build. Do not install this one.

Note

When the library opens the socket to the Action Request Server, it sends the 24-byte brand ID UR/L/1.5.0XXXXXXXXXXXXXX. The vision controller uses this string to select the matching protocol version. Because of this, the vision controller must run a Locator Studio version that supports protocol 1.5.0.

Note

This guide does not cover PolyScope 5 and CB-Series controllers. They do not support URCapX files. For them, use the Photoneo Robot module for PolyScope 5. It uses a different program format (.urp) and keeps the script as a file on the robot controller.

To check the system version on your robot, go to Main Menu → About:

The PolyScope X version is on the first line (Software):

2. Robot Controller Setup

2.1 Network Configuration

First, set the IP address of the robot controller port that connects to the Photoneo vision controller. Go to Main Menu → Settings:

Scroll down to Connection → Network. Select Static as the network method. Enter the IP address and the subnet mask of the robot controller. This guide uses 192.168.1.2 and 255.255.255.0. The network settings are password protected. Press Unlock and enter the administrator password before you change them.

Click Apply Configuration and then Lock and Close to confirm the changes.

Note

The subnet mask 255.255.255.0 is the same as a 24-bit subnet mask. See this table for more combinations: https://dnsmadeeasy.com/support/subnet

Example of a matching network configuration on the vision controller side:

• Vision controller IPv4 address: 192.168.1.1 / 24

• Robot controller IPv4 address: 192.168.1.2 / 24 (as configured in the previous step)

You can also ping the robot controller from the vision controller. Use the Test connection button on the Network page of the vision controller:

The result of the test (a ping command) is shown in a message: Robot available or Robot unavailable. If the robot is unavailable, check the cables and the network configuration.

2.2 Enabling Real-Time Data Exchange (RTDE)

Locator Studio reads the current joint positions and the tool pose of the robot through the Real-Time Data Exchange (RTDE) interface (port 30004). It uses these values to show the robot in the visualization on the vision controller. You do not install a Robot State Server program on the robot.

Go to Main Menu → Settings → Security → Services and make sure that Real-Time Data Exchange (RTDE) is enabled.

Note

The Services page is password protected. Press Unlock and enter the administrator password before you change an interface.

Note

The calibration request and the hand-eye scan request do not need RTDE. They send the robot pose in the request itself. The Locator Calibration node and a Locator Scan node with Camera = Robot-mounted both send get_actual_tool_flange_pose().

2.3 Installing the Locator Studio URCap

The URCap is one file, locator-studio-1.5.5.urcapx. Copy it to a USB flash drive. Connect the drive to the USB port of the teach pendant or of the robot controller. Then open Main Menu → System Manager:

In the left column of the System Manager, open the URCaps page and press + URCap. Select locator-studio-1.5.5.urcapx on the USB flash drive. The teach pendant asks you to confirm the installation.

Warning

When you install or uninstall a URCap, the system reloads. The confirmation dialog tells you: “After installation of the URCap, the system will automatically reload. This process cannot be canceled.” Save your work before you confirm. Do not install a URCap while a program is running.

After the reload, Photoneo Locator Studio is on the URCaps page, with its version, developer, contact information, copyright and license. On the same page, you can remove the URCap with Uninstall URCap.

Note

You install the URCap once on each robot controller. It does not belong to a program: it is not part of a .urpx file and it is not copied with a program. If the URCap is not installed, a program that uses the Photoneo nodes does not open correctly - the teach pendant shows these lines as a missing contribution. Install the URCap first, then import the programs.

2.4 Loading the Example Programs

These example programs are delivered with the URCap. Section 3.7 describes them.

• pho_main_basic_urc.urpx

• pho_main_basic_hand_eye_urc.urpx

• pho_main_basic_multi_vs_urc.urpx

• pho_main_change_bbox_urc.urpx

• pho_main_change_solution_urc.urpx

• pho_main_get_status_urc.urpx

• pho_get_running_solution_urc.urpx

• pho_main_reuse_scan_urc.urpx

• pho_multiview_static_urc.urpx

• pho_main_loc_MV_dyn_urc.urpx

• pho_calibration_auto_urc.urpx

• pho_calib_loc_hand_eye_urc.urpx

Copy the .urpx files to a USB flash drive and open Main Menu → System Manager. Press + Program, then Import Program, and select the example programs on the USB flash drive:

After the import, the Locator Studio example programs (*_urc) are on the Programs page of the System Manager. You can open them from there.

Note

A .urpx file contains a program and its application. The Photoneo settings are part of the application. When you import an example, you also import the settings that were saved with it: vision controller 192.168.1.1, vision system 1, and Camera = Fixed (except in the three examples that scan with a robot-mounted sensor: pho_main_basic_hand_eye_urc, pho_multiview_static_urc and pho_main_loc_MV_dyn_urc). After every import, check the settings page against your cell, as described in section 3.1.

Note

PolyScope X does not keep robot programs as files in a /programs directory (as PolyScope 5 does). It keeps them in an internal application store. Because of this, you cannot copy programs with scp or an FTP client. Import them from a USB flash drive in the System Manager, as described above.

Note

A PolyScope X program name can have a maximum of 30 characters. If the name is longer, the import fails with the error “Program name is too long” and the program does not load. On the robot, this looks like a damaged file. Use short names for renamed copies of the examples. The longest name in this delivery has 28 characters.

SSH access to the robot controller is available for diagnostics. It is disabled by default. To enable it, go to Main Menu → Settings → Security → Secure shell. There you set the port, the authentication method (password, key or both) and the authorized keys.

2.5 Tool (TCP) Setup

Locator Studio sends object poses in the robot base coordinate system. During the calibration and during a hand-eye scan, it must know where the robot flange is. The tool pose that the robot reports depends on the active end effector. Locator Studio works best with an all-zero tool, because it compensates the tool offset on the vision side. Use a zero tool for the calibration too.

On the left side, go to Application → End Effectors:

Make sure that the Tool_flange end effector has zero position and zero orientation values:

Note

The Locator Calibration node and the hand-eye variant of the Locator Scan node send get_actual_tool_flange_pose(). This pose does not depend on the active end effector. These requests are correct also when a non-zero tool is active.

Note

The picking motions are different. The example programs move the robot to the pose from Locator Studio with the TCP that is active at that moment. For picking, the active end effector must describe the real gripper. If you need both, activate your own end effector for your own movej / movel motions, and switch back to Tool_flange for the Photoneo requests.

3. Robot Module

Note

We strongly recommend that you read the Photoneo robotic API before this section.

The URCap gives you the Locator Studio API in two parts. The settings for the whole installation (where the vision controller is, which vision system is the default, how far to approach an object) are on one application node. Every request of the library is a program node that you add to the program tree. The rest is the same as in the script-only variant: the URCap adds the same photoneo_locator_X.script library to the program, and the nodes generate the same pho_* calls. A program works exactly like the same program written by hand.

3.1 The Photoneo Application Node

Open the Application tab on the left side of the teach pendant and select Photoneo Locator Studio. This page contains the complete configuration of the Robot module.

Setting	Delivered value	Meaning and generated code
IP address	192.168.1.1	Address of the Photoneo vision controller. Generated as IP_ADDRESS and passed to pho_wait_for_server.
Port	11003	Port of the Action Request Server on the vision controller.
Attempts	1	How many times pho_wait_for_server tries to open the socket. If all attempts fail, it reports PHO_COM_FAILURE and stops the program.
Vision System	1	The default vision system. Generated as VISION_SYS_ID. Every program node with Vision System = Default sends this value with its request, so this one setting changes the whole program.
Camera	Fixed	Fixed or Robot-mounted. With Robot-mounted, the Locator Scan node sends get_actual_tool_flange_pose() with the request. A scanner on the robot flange needs this. The setting affects only the Locator Scan node.
Debug	Off	On adds pho_enable_debug() to the program start. The library then writes every request and response to the log with textmsg.
Approach defaults - Offset, Method, Axis	0.1 m, Tool Offset, Z	Generated as APPR_OFFSET, APPR_METHOD and APPR_AXIS. Used by a Locator Approach Pose node with Offset = Approach defaults. See section 4.1.
Deapproach defaults - Offset, Method, Axis	0.2 m, Base Offset, Z	Generated as DEAPPR_OFFSET, DEAPPR_METHOD and DEAPPR_AXIS. Used by a Locator Approach Pose node with Offset = Deapproach defaults.

When the program starts, before the Before Start sequence runs, the application node adds the complete photoneo_locator_X.script library to the program. After the library, it adds the configuration and the connect call. With the delivered values, the end of this generated code is:

# Photoneo Locator Studio UR/L/1.5.0 - configuration from the Photoneo application node
global IP_ADDRESS = "192.168.1.1"
global VISION_SYS_ID = 1
global APPR_OFFSET = 0.1
global APPR_METHOD = "Tool Offset"
global APPR_AXIS = "Z"
global DEAPPR_OFFSET = 0.2
global DEAPPR_METHOD = "Base Offset"
global DEAPPR_AXIS = "Z"
# Connect to the Vision Controller
pho_wait_for_server(IP_ADDRESS, 11003, 1)

Note

The connect call is part of the generated program start, so every program start opens a new connection (pho_wait_for_server closes the old socket before it opens a new one). You do not add anything to Before Start, and a Photoneo node does not have to be the first line of the program.

Note

If the socket cannot be opened, the library sets PHO_ERR_CODE to 3 (communication failure) and stops the program. When the connection is open, the Deployment page of Locator Studio shows the Action Request Client as CONNECTED (green).

Note

The global variables in the generated code are normal program variables. A program can change them while it runs. The multi-vision-system example and the reuse-scan example use this to switch the vision system: all nodes keep Vision System = Default, and the program assigns a new value to VISION_SYS_ID. This changes the vision system for all requests at once.

3.2 The Photoneo Program Nodes

The seven Photoneo nodes are in the Toolbox of the program editor, in the URCaps category. Each one has the Photoneo icon. A Photoneo node uses one line of the program tree and shows its settings on this line, so you can see what a node does without opening it.

Program node	Purpose	Generated requests
Locator Scan	Scan and localize, trigger a MultiView capture, or localize again on the last scan. Optionally wait for the result.	pho_request_scan(), pho_trigger_scan(), pho_reuse_scan(), pho_wait_for_scan_completion()
Locator Get Objects	Read the poses of the localized objects. Copy the first pose and the number of objects to two program variables.	pho_request_get_single_object(), pho_request_get_all_objects(), pho_request_get_objects()
Locator Approach Pose	Calculate an offset pose from a localized pose (approach and deapproach of a pick), with the reachability check of the library.	pho_get_offset()
Locator Solution	Change, start or stop a solution, or read which solution runs on the vision controller.	pho_request_change_solution(), pho_request_start_solution(), pho_request_stop_solution(), pho_request_running_solution()
Locator Calibration	The four calibration steps: start, add a point at the current robot pose, save, stop.	pho_calib_start(), pho_calib_add_point(), pho_calib_save(), pho_calib_stop()
Locator Vision System	Change the bounding box of a vision system, or read its processing state and the number of objects.	pho_request_change_bbox(), pho_request_get_vs_status()
Locator Comm Check	Check that the vision controller answers.	pho_request_comm_check()

Note

Section 3.4 lists the requests behind these nodes with their request IDs. Do not edit the library. The URCap adds it to the program when the program starts. It is not stored as a node in the program.

Note

The nodes do not check the result for you. When a request finds nothing or fails, pho_object_poses[0] is p[0,0,0,0,0,0]. Before the robot moves, check the number of objects and PHO_ERR_CODE with a native If node, as all delivered examples do.

3.2.1 Locator Scan

Starts the sensor and the localization. This is the only node that uses the Camera setting of the application node.

Field	Options	Effect
Request	Scan, Trigger scan, Localize again	pho_request_scan - scan and localize; the program can wait for the result. pho_trigger_scan - capture only, for a MultiView sequence. pho_reuse_scan - localize again on the data of the last scan.
Vision System	Default, or Select and an ID	Default sends VISION_SYS_ID from the application node, so the node follows the setting. Select always uses the ID next to it.
Result	Wait, Continue	Wait adds pho_wait_for_scan_completion(). Continue does not wait. Use it only with an extrinsic sensor or for dynamic MultiView. With a hand-eye sensor, keep the robot still until the scan response arrives. A later node collects the response (for example, another Locator Scan node with Result = Wait, or any other request).
Timeout	0 (delivered)	In seconds. With 0, the node calls pho_wait_for_scan_completion() without an argument, which waits without a time limit. Any other value is passed as the timeout.

With a fixed camera and the delivered settings, a scan node with Result = Wait generates:

pho_request_scan(VISION_SYS_ID)
pho_wait_for_scan_completion()

With Camera = Robot-mounted, the same node sends the flange pose with the request. For a scan, the pose is a keyword argument. For a trigger or a reuse, it is a positional argument, as the library declares it:

pho_request_scan(VISION_SYS_ID, tcp_pose=get_actual_tool_flange_pose())
pho_trigger_scan(VISION_SYS_ID, get_actual_tool_flange_pose())

Note

All three scan requests are non-blocking. pho_wait_for_scan_completion collects the response. With a hand-eye sensor, keep the robot still until the scan response arrives. With an extrinsic sensor, the robot can move in the meantime if it stays out of the scanned scene. The only exception is dynamic MultiView, where the sensor scans while the robot moves. If a response is still pending, every other request collects it before it sends its own request, so no response is lost. If pho_wait_for_scan_completion is called when no scan request is pending, it shows a Program flow error message and halts the program. Do not use Result = Wait without a scan request before it.

3.2.2 Locator Get Objects

Reads the localized poses from the vision controller and makes them available to the rest of the program.

Field	Options	Effect
Request	Single object, All objects, N objects	pho_request_get_single_object, pho_request_get_all_objects, or pho_request_get_objects with a number of objects.
Objects	2 (delivered); a Number or a variable	The number of objects for the N objects request. Type a number on the node, or select a program variable. The get-status example uses pho_ready, which a Locator Vision System status node writes.
Vision System	Default, or Select and an ID	As for the Locator Scan node.
writes	pho_object (pose), pho_found (integer)	pho_object is the first localized pose, pho_object_poses[0]. pho_found is pho_number_of_objects. The node declares both variables, so you can select them in the native Move and If nodes.

A node that requests two objects generates the request and the two assignments:

pho_request_get_objects(VISION_SYS_ID, 2)
global pho_found = pho_number_of_objects
global pho_object = pho_object_poses[0]

Note

The declared pose is only the first object. A pick loop that empties the bin reads the list itself. The delivered examples add a native Assignment node pho_object_pose = pho_object_poses[increment] in the loop and use this variable in the Locator Approach Pose node. The loop counts with pho_found.

Note

The node declares the two variables (it does not only assign them), so you can select them in the native Move and If nodes. The program start also sets them to 0 and p[0,0,0,0,0,0]. If the program reads one of them before the node runs, it gets a zero pose and not the runtime error “is not initialized to a value”. If you rename them in the node, they are renamed everywhere they are used.

3.2.3 Locator Approach Pose

Locator Studio sends the pose of the object itself. Unlike Bin Picking Studio, it does not plan a trajectory. The robot program controls all motion: it calculates an approach pose above the object, moves there, moves to the object, closes the gripper and moves away. This node calculates the offset and runs the reachability check of the library.

Field	Options	Effect
Object pose	A pose variable that is declared above the node	The pose for the offset calculation: pho_object from a Locator Get Objects node, or pho_object_poses[increment] copied by an Assignment node, as in all delivered pick loops.
writes	pho_approach (pose), pho_approach_ok (boolean)	The offset pose, and the result of the reachability check (pho_reachable of the library).
Offset	Approach defaults, Deapproach defaults, This node	Where the distance, the method and the axis come from: one of the two blocks of the application node, or the three fields on the node.
Distance, Method, Axis	0.1 m, Tool Offset, Z	Used when Offset is This node. The methods are Base Offset, Base Plane, Tool Offset and Tool Plane (see section 4.1).

A node with the approach defaults generates (the delivered examples name the output variables approach and approach_ok):

global approach = pho_get_offset(pho_object_pose, APPR_OFFSET, APPR_METHOD, APPR_AXIS)
global approach_ok = pho_reachable

Warning

pho_get_offset checks the object pose, the offset pose and two safety poses with is_within_safety_limits. If one of them is out of reach, it shows a blocking error message “One or more calculated poses are not reachable” (title “Photoneo: Reachability error”) and returns no value, so the assignment of the node is not done. An error message stops the program. When the program stops, the socket closes, and the vision controller reports that the robot disconnected. Check the number of objects before the approach.

Note

The node copies the result of the check to the boolean variable that it declares. Your program can check it with a native If node. The program start also initializes the target pose, for the same reason as the Get Objects variables.

3.2.4 Locator Solution

Solution management: read which solution is deployed on the vision controller, and start, stop or change the solution from the robot program.

Field	Options	Effect
Request	Change solution, Start solution, Stop solution, Running solution	pho_request_change_solution, pho_request_start_solution, pho_request_stop_solution and pho_request_running_solution.
Solution	1 (delivered); a Number or a variable	The solution ID for the change and start requests. The delivered examples keep it in the SOLUTION_ID variable and change this variable in the program, so the node reads the variable.
writes	pho_solution (integer)	Only for the Running solution request: the ID from the vision controller (pho_running_solution). Without a result variable, the node is not valid.

pho_request_change_solution(SOLUTION_ID)
pho_request_running_solution()
global pho_solution = pho_running_solution

3.2.5 Locator Calibration

Calibration of a vision system from the robot program: one node for each step. Put an Add point step at each taught calibration pose.

Field	Options	Effect
Step	Start, Add point, Save, Stop	pho_calib_start, pho_calib_add_point, pho_calib_save and pho_calib_stop. Only the Start step uses the solution and the vision system.
Solution	1 (delivered)	The solution that the calibration belongs to.
Vision System	Default, or Select and an ID	The vision system to calibrate.

pho_calib_start(1, VISION_SYS_ID)
pho_calib_add_point(get_actual_tool_flange_pose())
pho_calib_save()
pho_calib_stop()

Note

The Add point step always sends the flange pose, never the TCP, for a static scanner and for a robot-mounted scanner. The calibration on the vision controller expects this pose. This step has no parameters to set.

3.2.6 Locator Vision System

The two requests for a vision system (not for a solution): change its bounding box, or read the progress of its localization.

Field	Options	Effect
Request	Change bounding box, Get status	pho_request_change_bbox or pho_request_get_vs_status.
Bounding box	1 (delivered); a Number or a variable	The bounding box to use. The change-bbox example keeps it in BBOX_ID and changes this variable in the program, so the node reads the variable.
Vision System	Default, or Select and an ID	As for the Locator Scan node.
writes	pho_vs_status (integer), pho_localized, pho_ready	Only for the Get status request: pho_process_state, pho_num_localized and pho_num_ready. Without the state variable, the node is not valid.

pho_request_change_bbox(VISION_SYS_ID, BBOX_ID)
pho_request_get_vs_status(VISION_SYS_ID)
global pho_vs_status = pho_process_state
global pho_localized = pho_num_localized
global pho_ready = pho_num_ready

Note

You can send a status request repeatedly at short intervals while the localization runs. You can use pho_ready (the number of objects that are ready to be picked) directly in the Objects field of a Locator Get Objects node. The pho_main_get_status_urc example does this.

3.2.7 Locator Comm Check

Asks the vision controller if it answers, and writes the answer to PHO_ERR_CODE. The node has no parameters.

pho_request_comm_check()

3.3 Validation and Program Tree Labels

A Photoneo node checks its own parameters. If a node is not valid, the teach pendant marks its program line and does not run the program. The messages are:

• Vision System must be 1 or higher - a selected vision system ID is missing or is not a positive whole number (Locator Scan, Locator Get Objects, Locator Calibration, Locator Vision System).

• Timeout cannot be negative - Locator Scan.

• Number of objects must be 1 or higher - Locator Get Objects with Request = N objects.

• Select a pose variable declared above this node - Locator Approach Pose without an object pose, or with a pose that is no longer a valid program variable.

• Offset must be a number - Locator Approach Pose with Offset = This node.

• Solution must be 1 or higher - Locator Solution (Change solution, Start solution) and Locator Calibration (Start).

• Bounding box must be 1 or higher - Locator Vision System, Change bounding box.

• No variable for the result - a request that returns a value has no variable for it (Locator Solution with Running solution; Locator Vision System with Get status).

Note

If you rename a variable, the node reports it as not valid and does not follow the new name. For example, if you rename the pose that a Locator Approach Pose node reads, open the node and select the pose again.

Each node also writes its own line in the program tree, so you can read a Locator program without opening the nodes. Examples: Scan, default VS, wait, Get 2 objects -> pho_object, pho_found, approach = approach of pho_object_pose (approach defaults), Status of default VS -> pho_vs_status, Start calibration, solution 1, default VS.

3.4 The Requests Behind the Nodes

This table shows which node sends which request of the Locator Studio protocol. The ID column shows the request ID that is sent over the Photoneo communication protocol. You also see this ID in the log of the vision controller. For details about each request, see Action requests.

Request	ID	Library function	Sent by
Connect to the Action Request Server	-	pho_wait_for_server(server_ip, port, max_attempt)	The Photoneo application node, at the program start
Scan and localize	19	pho_request_scan(vision_sys_id, tcp_pose=PHO_EXTRINSIC_VS)	Locator Scan, Request = Scan
Wait for scan	-	pho_wait_for_scan_completion(timeout=-1)	Locator Scan, Result = Wait
Trigger scan (MultiView)	30	pho_trigger_scan(vision_sys_id, tcp_pose=PHO_EXTRINSIC_VS)	Locator Scan, Request = Trigger scan
Reuse scan (localize on the last scan)	31	pho_reuse_scan(vision_sys_id, tcp_pose=PHO_EXTRINSIC_VS)	Locator Scan, Request = Localize again
Get objects	20	pho_request_get_objects(vision_sys_id, num_of_req_objects)	Locator Get Objects, Request = N objects
Get all objects	20	pho_request_get_all_objects(vision_sys_id)	Locator Get Objects, Request = All objects
Get single object	20	pho_request_get_single_object(vision_sys_id)	Locator Get Objects, Request = Single object
Get vision system status	22	pho_request_get_vs_status(vision_sys_id)	Locator Vision System, Request = Get status
Change bounding box	33	pho_request_change_bbox(vision_sys_id, bbox_id)	Locator Vision System, Request = Change bounding box
Calibration start	25	pho_calib_start(solution_id, vision_sys_id)	Locator Calibration, Step = Start
Calibration add point	5	pho_calib_add_point(tcp_pose)	Locator Calibration, Step = Add point
Calibration save	27	pho_calib_save()	Locator Calibration, Step = Save
Calibration stop	26	pho_calib_stop()	Locator Calibration, Step = Stop
Change solution	9	pho_request_change_solution(solution_id)	Locator Solution, Request = Change solution
Start solution	10	pho_request_start_solution(solution_id)	Locator Solution, Request = Start solution
Stop solution	11	pho_request_stop_solution()	Locator Solution, Request = Stop solution
Get running solution	12	pho_request_running_solution()	Locator Solution, Request = Running solution
Communication check	100	pho_request_comm_check()	Locator Comm Check
Offset a pose (no request is sent)	-	pho_get_offset(target, offset_value, method, axis)	Locator Approach Pose

Note

These functions are defined in the API section of photoneo_locator_X.script. The URCap adds this file to the program without changes. Do not edit it.

Note

One library function has no node: pho_get_approach(target, offset_z), which only adds an offset to the base Z coordinate. A Locator Approach Pose node with Method = Base Offset and Axis = Z does the same and also checks reachability.

3.5 Result Variables

The requests do not return values. They write their results to global variables of the library. The robot program can read these variables at any time after the request. A variable keeps its value until the next request changes it. The nodes that produce a result also copy it to a variable that they declare. Because of this, you can select the result in the native Move and If nodes. For the meaning and the units of the values sent by the vision controller, see Info data.

Library variable	Written by	Meaning
PHO_ERR_CODE	every request	Response code of the last request (see section 3.6)
PHO_OCCURRED_ERR	every request	True when the last request returned a response code other than 0
pho_object_poses	Locator Get Objects	List of up to 100 object poses in the robot base coordinate system (p[x,y,z,rx,ry,rz], [m], [rad]). The node copies pho_object_poses[0] to pho_object. A pick loop reads the list itself.
pho_number_of_objects	Locator Get Objects	Number of object poses that were received. The node copies it to pho_found.
pho_object_pose	Locator Get Objects, Request = Single object	Copy of the first received pose, written by the library
pho_dimensions_x, pho_dimensions_y	Locator Get Objects	Width and depth of each object [mm] - only for localization without a CAD model
pho_dimensions_rot	Locator Get Objects	Rotation of each object around Z [deg] - only for localization without a CAD model
pho_nn_label	Locator Get Objects	Class label from an AI solution
pho_max_height, pho_angle	Locator Get Objects	Maximum Z height [mm] and tilt angle [deg], used by layer solutions
pho_num_localized	Locator Vision System, Get status	Number of localized objects. The node copies it to pho_localized.
pho_num_ready	Locator Vision System, Get status	Number of objects that are ready to be picked. The node copies it to pho_ready.
pho_process_state	Locator Vision System, Get status	0 = processing has finished, 1 = localization is still running. The node copies it to pho_vs_status.
pho_reachable	Locator Approach Pose	True when all four calculated poses are reachable. The node copies it to pho_approach_ok.
pho_calib_acc	Locator Calibration, Save	Calibration accuracy sent by the vision controller [µm]
pho_camera_pose	Locator Calibration, Save	Camera pose that results from the calibration
pho_running_solution	Locator Solution, Running solution	ID of the solution that is deployed on the vision controller. The node copies it to pho_solution.

Note

The library converts pho_dimensions_rot and pho_angle from milliradians (as sent) to degrees. All other values are stored as they are sent.

3.6 Response Codes

Every request writes its result to PHO_ERR_CODE. If the code is not 0, the request also sets PHO_OCCURRED_ERR. The library defines a named constant for each code. Your program can compare the code with the name instead of the number, for example if PHO_ERR_CODE == PHO_NO_OBJ_RUN:. Codes 3 and 4 stop the program. All other codes are only reported, and the program continues, so that it can react. For the full description of each code, see Error codes.

Code	Constant	Meaning
0	PHO_NO_ERROR	The request was successful
1	PHO_SERVICE_ERR	Service error - the process that handles the request is not available (for example, no LS solution is deployed)
2	PHO_UNKNOWN_REQ	The vision controller does not know the request
3	PHO_COM_FAILURE	Communication failure - the program stops
4	PHO_BAD_DATA	Incorrect data received - the program stops
5	PHO_TIMEOUT	The response did not arrive within the timeout
450 - 459	PHO_INVALID_SOL … PHO_SOL_FORBIDDEN	Solution management: invalid solution ID, another solution is running, start or stop error, solution incomplete, invalid brand ID, solution already running, operation forbidden
460 - 469	PHO_INVALID_VS … PHO_CALIB_FORBIDDEN	Calibration: invalid vision system, calibration already running or not running, stop or start error, calibration disabled, not enough calibration points, calibration accuracy above the allowed threshold, scanner not available, calibration forbidden
500	PHO_VS_NOT_FOUND	The requested vision system does not exist
501	PHO_EMPTY_SCENE	Empty scene
502	PHO_NO_OBJ_RUN	No object found yet, the localization is still running
503	PHO_NO_OBJ_STOP	No object found, the localization has finished
504	PHO_REJECT_RUN	All objects found so far were rejected, the localization is still running
505	PHO_REJECT_STOP	All objects were rejected, the localization has finished

Note

There is no Photoneo node for error handling. Check the code with a native If node and the expression PHO_ERR_CODE != PHO_NO_ERROR, as all delivered examples do. Put your own reaction (a retry, a message, a safe position) in this branch.

3.7 Example Programs

Twelve .urpx example programs are delivered with the URCap. They are the same twelve programs as in the script-only variant, built from Photoneo nodes. The library and the configuration moved to the Photoneo application node, and each request that was written by hand is now a node. Everything else is the same: waypoints, moves, folders, loops, the PHO_ERR_CODE checks and the gripper comments. All main examples have the same structure: the Photoneo pick and place loop folder contains the Picking and Placing folders. The application node connects to the vision controller before the program body runs.

Example program	Description
pho_main_basic_urc	The basic template - start here. A Locator Scan node with Result = Wait, a Locator Get Objects node that requests 2 objects, and a pick loop. The loop reads pho_object_poses[increment] and calculates the offsets with two Locator Approach Pose nodes: one with the approach defaults and one with the deapproach defaults. The PHO_ERR_CODE check after the request is a native If node with an expression written by hand, as in the script-only variant (see section 3.6).
pho_main_basic_hand_eye_urc	The same program for a scanner on the robot flange. The only difference is the application node: Camera = Robot-mounted. Because of this, the scan node sends pho_request_scan(VISION_SYS_ID, tcp_pose=get_actual_tool_flange_pose()) from the taught scanning pose. It requests 3 objects.
pho_main_basic_multi_vs_urc	Switches between two vision systems. All nodes keep Vision System = Default. An If / ElseIf at the end of the loop sets VISION_SYS_ID to 2 or 1. This one assignment changes the vision system for the scan, the Get objects request and all other nodes that use the default.
pho_main_change_bbox_urc	Changes the region of interest. A Locator Vision System node with Request = Change bounding box reads the ID from the BBOX_ID variable, which the program switches between 1 and 2. Use this when the scene has not changed, but the localization must run again in a different region. Prepare a vision system with at least two bounding boxes.
pho_main_change_solution_urc	All four solution requests as four Locator Solution nodes: read the deployed solution (Running solution, to pho_solution), Stop solution, Start solution and Change solution. The last two use the SOLUTION_ID variable, which the program switches.
pho_main_get_status_urc	Polls the localization. Four Locator Vision System nodes with Request = Get status write pho_vs_status, pho_localized and pho_ready. The Locator Get Objects node takes the number of objects from the pho_ready variable, so the program requests exactly the number of objects that are ready to be picked. Programs usually use these values to decide when to read the poses.
pho_get_running_solution_urc	Both status requests in one loop: a Locator Vision System status node and a Locator Solution node with Request = Running solution. The Locator Get Objects node uses All objects instead of a fixed number. This is the only example that asks which solution runs on the vision controller.
pho_main_reuse_scan_urc	Localizes again on data that was already captured. Use this when the scene has not changed, but the localization must run with a different configuration. When VISION_SYS_ID is 1, the program uses a Locator Scan node with Request = Scan, Result = Wait. When it is 2, it uses Request = Localize again, Result = Continue, as in the script-only variant. The program switches VISION_SYS_ID after each pick cycle.
pho_multiview_static_urc	Static MultiView (meshing): the program combines several scans before the localization runs. This helps with complex scenes and large objects. The robot stops at each scanning position, and a Locator Scan node with Request = Trigger scan captures there. A last node with Request = Scan does not trigger the projector. It only localizes on the combined data. Camera = Robot-mounted, so every trigger sends its flange pose. Scan limit: for best performance, use fewer than 10 scans in total.
pho_main_loc_MV_dyn_urc	Dynamic MultiView: Photoneo Instant Meshing with MotionCam-3D. A parallel thread contains a Locator Scan node with Request = Trigger scan and Result = Wait. While MESH_DYNAMIC is True and the robot moves along the scanning trajectory, the thread runs this node again and again, with a pause of CAPTURE_GAP seconds (0.5 s in the delivered program) after each capture. Then a single Scan node starts the localization. Requirements: MotionCam-3D is required. Standard PhoXi 3D Scanners do not support dynamic scanning. Trajectory: keep the scanning trajectory smooth, avoid sudden rotations and keep the scanned area in the field of view, so that the tracking is not lost. Scan limit: use no more than 60 scans in total.
pho_calibration_auto_urc	Automatic calibration of a statically mounted scanner, with thirteen Locator nodes: Stop solution and Start calibration in Before Start, nine Add point steps (one in each of the folders 1. Calibration Pose to 9. Calibration Pose), then Save and Stop. Requirements: The initial calibration of the vision system is done and confirmed manually in Locator Studio. Automatic calibration is enabled for the vision system. Otherwise, pho_calib_start returns error 465. The nine calibration poses are the same robot poses as in the initial calibration. The automatic calibration reuses the calibration poses of the last calibration done by the operator. Calibration accuracy: as a general rule, the calibration error must be less than 3 mm. A larger error usually shows a systematic problem in the calibration setup. Important: the scanner is statically mounted, so the calibration object is the calibration ball mounted on the flange or gripper. The ball moves with the robot through the calibration poses. It must stay in the same place on the flange or gripper as in the initial calibration - do not remount or move it in between.
pho_calib_loc_hand_eye_urc	The same procedure for a hand-eye scanner (mounted on the robot flange), controlled from Locator Studio. The program contains only the nine Add point steps. You start, save and stop the calibration on the vision controller. Each step sends the sensor position with pho_calib_add_point(get_actual_tool_flange_pose()).

Note

You provide the gripper commands. Where a delivered example has a “Set gripper command” comment, add your own gripper node or script. The examples do not control a gripper.

4. Runtime

When the solution is completely configured on the vision controller, do the last steps on the robot side and run the Locator Studio program.

4.1 Approach and Deapproach Offset Parameters

Locator Studio sends the pose of the object. The robot must not move straight to it. The example programs approach the object from a distance and move away in the same way. The two blocks of the Photoneo application node contain the values for this:

Application setting	Delivered value	Declared global variable
Approach defaults - Offset	0.1	APPR_OFFSET - approach distance in meters
Approach defaults - Method	Tool Offset	APPR_METHOD
Approach defaults - Axis	Z	APPR_AXIS
Deapproach defaults - Offset	0.2	DEAPPR_OFFSET - deapproach distance in meters
Deapproach defaults - Method	Base Offset	DEAPPR_METHOD
Deapproach defaults - Axis	Z	DEAPPR_AXIS

A Locator Approach Pose node uses one of the two blocks (its Offset field), or its own values when Offset is This node. The methods are:

• Base Offset - adds the offset along the selected axis in the base coordinate system

• Base Plane - sets the coordinate along the selected axis to the offset value (base coordinate system)

• Tool Offset - moves the pose back by the offset along the selected axis of the object (tool) coordinate system

• Tool Plane - calculates where the Z axis of the object crosses the plane at the offset value along the selected base axis

Note

The two Base methods use an axis of the base coordinate system. The two Tool methods use the axis of the object, so the robot approaches a tilted object along its own direction. The correct method depends on the gripper and on the application. The delivered examples approach with Tool Offset and move away with Base Offset.

Note

When you change a value on the application node, you change every node that uses the defaults, in every program of this application. Use Offset = This node when one line must be different.

4.2 Teach Positions

Open pho_main_basic_urc or another template. Before you run the program, touch up these five poses to fit your cell: Scanning, Pick_start, Before_place, Place and Deappr_place. The robot scans from the Scanning pose. It returns to Pick_start before it approaches the next object.

The MultiView examples use the scanning poses Start, Middle and End instead of Scanning. The calibration examples use Calib_Home and nine more poses, Calib_Pose_1 to Calib_Pose_9, one in each of the folders 1. Calibration Pose to 9. Calibration Pose.

Note

Do not rename these waypoints. The program uses their names. If you rename a waypoint, the move nodes have no target.

4.3 Runtime Prerequisites

Before you run the Locator Studio program from the robot side for the first time, make sure that:

• the Locator Studio solution is correctly configured on the vision controller

• the network setup on the robot side is complete

• RTDE is enabled (section 2.2)

• the Locator Studio URCap is installed and is on the URCaps page (section 2.3)

• the Photoneo application node has the IP address of your vision controller and the correct default vision system, and the Camera setting matches your mounting (section 3.1)

• all vision systems in the solution are calibrated

• all poses in the main program are touched up correctly

• the approach and deapproach offsets are set for your gripper (section 4.1)

• the gripper commands are ready and work

• no program line is marked as not valid (section 3.3)

4.4 Running the pho_main_basic_urc Program

Deploy your solution. Until the robot program connects, the Deployment page shows the Action Request Client as DISCONNECTED:

Note

We strongly recommend that you set the Speed slider on the teach pendant to 20% before you run the program for the first time.

Start the program. When the connection is open, the Action Request Client status changes to CONNECTED. The sensor takes the first scan and the localization starts.

If there is a pickable object in the scene and the robot controller receives its pose, the robot starts to move to the first object. The Photoneo nodes add these statements to the pick loop:

pho_request_scan(VISION_SYS_ID)
pho_wait_for_scan_completion()
pho_request_get_objects(VISION_SYS_ID, 2)
global pho_found = pho_number_of_objects
global pho_object = pho_object_poses[0]
...
global pho_object_pose = pho_object_poses[increment]
global approach = pho_get_offset(pho_object_pose, APPR_OFFSET, APPR_METHOD, APPR_AXIS)
global approach_ok = pho_reachable
movej(approach,r=0.0)
movel(pho_object_pose,a =0.1, v =0.5 )
global deapproach = pho_get_offset(pho_object_pose, DEAPPR_OFFSET, DEAPPR_METHOD, DEAPPR_AXIS)
global deapproach_ok = pho_reachable
movel(deapproach,a=1.2,v=0.5)

Note

To see the generated script of a program on the teach pendant, use View script in the System Manager. This is the fastest way to check what a node sends.

If everything looks correct, continue to move the robot to the first object and check the path. If the robot stops too far from the object or pushes the object too deep, adjust the object origin or the tool setup.

If the robot movement is correct, set up your own placing routine and slowly increase the speed to 100%.

The Photoneo Universal Robots interface now works. To improve your application, use the example programs in section 3.7 and the node reference in section 3.2.

5. Robot Module Update

To update the Robot module to a version that matches your Locator Studio version, do these steps:

1. Install the new URCap. Copy the new .urcapx file to a USB flash drive and install it as described in section 2.3. The new URCap replaces the installed URCap with the same vendor and ID. The system reloads once.

2. Open and save each program once. The URCap updates the nodes of a program when the program is loaded for the first time. Open every Locator program, check that no line is marked as not valid, and save it. From 1.5.0 to 1.5.5, these changes were made: the hand-eye switch of the Locator Scan node moved to the Camera setting of the application node, the Locator Approach Pose node got the reachability variable, and its “use application defaults” switch became the three-way Offset field.

3. Check the settings page. A new Robot module version can add settings. The update fills them with default values, which are not always correct for your cell.

4. Check the API changes. Read the API changes of the new version and check the nodes that use them.

You do not replace a library file or edit a Script node. The URCap adds the library to the program, so after you update the URCap, every program on the robot controller uses the new library at its next start. This is the main difference from the script-only variant, where every program contains its own copy of the library and you must replace it in each program.

The URCap version is shown on the URCaps page of the System Manager (Photoneo / Locator Studio 1.5.5 for this build). The brand ID that the Robot module sends to the vision controller is described in section 1: UR/L/1.5.0 for the 1.5 library.

Note

A URCap that is built for a newer PolyScope X contribution API may not install on an older robot controller. If you update PolyScope X and the URCap together, install the PolyScope X update first.

6. Version and Brand ID

Item	Value
URCap version	1.5.5 (locator-studio-1.5.5.urcapx)
Robot module protocol version	1.5.0 (photoneo_locator_X.script)
Locator Studio	1.5
Brand ID (sent by pho_wait_for_server)	UR/L/1.5.0XXXXXXXXXXXXXX
Action Request Server port	11003
Robot state (RTDE)	Port 30004 on the robot controller - read by the vision controller, no robot program needed
PolyScope X SDK / contribution API	6.0.27 / 42.2.3

7. Migration

For the changes in the communication interface, see Migration from LS 1.4.x to LS 1.5.x. For the changes between URCap versions 1.5.0 and 1.5.5, see section 5.